What changed and why

pipeline.failed previously carried only pipeline_wall_clock_ms + err, giving operators no signal about which stage threw or how long it had been running — they had to scroll back through pipeline.stage lines and mentally reconstruct the static stage order to diagnose a failure.

This adds a StageTracker cursor to runPipeline. Each of the seven timeStage calls and the inline prompt.build site receive it as an optional fourth argument: on stage entry the tracker is set, on success it is cleared, and on throw it is left intact. The outer catch reads stageTracker.active and conditionally spreads failed_stage + failed_stage_delta_ms into the pipeline.failed line. Both fields are omitted when no timed stage was in flight (an early failure before any stage, or after all stages succeeded).

One correctness detail: the trackingComment.finalize inner catch swallows its error and continues, so stageTracker.active is explicitly cleared there — otherwise a subsequent throw would be mis-attributed to finalize.

The change is additive: success path, control flow, and return values are unchanged. timeStage's tracker argument is optional, so every existing caller stays valid. New strict PipelineFailedLogSchema in src/core/log-fields.ts mirrors PipelineCompletedLogSchema, pinning the new fields so a rename or stray field trips the co-located test.

Flow

flowchart TD
  RP["runPipeline creates a StageTracker"]:::new
  STG["timeStage stage fn tracker"]:::keep
  SUCC["on success: tracker cleared<br/>pipeline.completed unchanged"]:::keep
  THROW["on throw: tracker keeps stage and startedAt"]:::new
  FAIL["pipeline.failed<br/>err + pipeline_wall_clock_ms<br/>+ failed_stage + failed_stage_delta_ms"]:::new
  RP --> STG
  STG --> SUCC
  STG --> THROW
  THROW --> FAIL
  classDef new fill:#196f3d,color:#ffffff
  classDef keep fill:#2c3e50,color:#ffffff

Changes

• src/core/log-fields.ts — StageTracker interface + createStageTracker(); timeStage gains an optional tracker param (set on entry, clear on success, retain on throw, re-throw unchanged); strict PipelineFailedLogSchema + PipelineFailedLog.
• src/core/pipeline.ts — create the tracker, thread it to the 7 timeStage calls + prompt.build, clear it in the finalize inner catch, and spread the two fields in the outer catch.
• test/core/log-fields.test.ts — PipelineFailedLogSchema drift suite (valid; camelCase/extra-field/negative/wrong-event-literal/missing-required rejected) + timeStage tracker suite (clear-on-success, retain-on-throw, null-initial, no-tracker backward-compat).
• docs/operate/observability.md — pipeline.failed row documents the two new fields.

Test plan

• 11 new log-fields tests pass; each runPipeline-exercising handler test (review/implement/resolve) passes in isolation
• typecheck / lint / format / docs:build clean
• Full bun test failure count is baseline-identical (no new failures); the only combined-run failures are pre-existing cross-file mock pollution the isolated CI runner avoids

Closes #226

Summary by CodeRabbit

• Documentation

  • Updated pipeline observability documentation with expanded failure event schemas and detailed payload field descriptions.

• New Features

  • Enhanced pipeline failure diagnostics: failures now record which stage was active at time of failure and the elapsed duration, enabling faster root cause analysis and debugging.